home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 5 / Amiga Tools 5.iso / tools / system-tools / smartcrash / smartcrash.doc < prev    next >
Text File  |  1996-02-26  |  19KB  |  408 lines
  1.                                                                 26-Feb-1996
  2. Documentation for
  3.  
  4.                         ==========================
  5.                         ====  SmartCrash 1.1  ====
  6.                         ==========================
  7.                 Copyright © 1995-1996 PitPlane Productions
  8.  
  9.              IMPORTANT! Please read copyrights, disclaimer and
  10.                 license parts of this document before use.
  11.  
  12.  
  13.  
  14.     *** What is SmartCrash? ***
  15.  
  16.     o SmartCrash is a system crash requester replacement. SmartCrash
  17.       requires Kickstart 2.0 or better.
  18.  
  19.  
  20.     *** Why SmartCrash? ***
  21.  
  22.     o This is the main reason:
  23.                 ___________________________________________
  24.                 |Software Failure                       [_]
  25.                 ||¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯||
  26.                 ||   causefailpro                        ||
  27.                 ||   Program failed (error #80000005).   ||
  28.                 ||   Wait for disk activity to finish.   ||
  29.                 ||_______________________________________||
  30.                 |.---------.                    .--------.|
  31.                 || Suspend |                    | Reboot ||
  32.                 |`---------'                    `--------'|
  33.                 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  34.                    FIGURE 1: Pathetic OS crash requester
  35.  
  36.  
  37.     o Kickstart 2.0 introduced great crash requester. System didn't just
  38.       guru if something went wrong, it displayed nice little requester
  39.       instead. So what!? Yes, there is a "Suspend" -gadget in the requester
  40.       but even so it isn't the best possible. It should be more
  41.       informative. It should have more buttons to play with. Here
  42.       SmartCrash comes in.
  43.  
  44.  
  45.     o This tool is FREEWARE!! (see license)
  46.     o SmartCrash is 100% assembler.
  47.     o SmartCrash executable is only about 4½ K!
  48.     o Uses very little extra memory!
  49.     o Uses SegTracker information if available!
  50.     o Support for both intuition and reqtools.library requesters.
  51.     o ReqTools requester's font can be configured.
  52.     o In ReqTools SmartCrash uses key shortcuts!!
  53.     o Falls back to alert message if no requester can be created.
  54.     o Has lots of new buttons. Just try them!!
  55.     o "Skip" -button can skip failed instructions.
  56.     o Displays _loads of_ information about the failure.
  57.     o SmartCrash should be compatible with future kickstarts.
  58.     o Enforcer hit free (obvious!)
  59.  
  60.  
  61.     *** Notes ***
  62.  
  63.     o SmartCrash DOES NOT...
  64.  
  65.     ...replace GURUs!
  66.     ...do any resource tracking!
  67.  
  68.     o SmartCrash has been tested on following systems:
  69.  
  70.       A1200 4/160 MB, 68020 @ 14MHz and
  71.       A1200 10/540 MB, Blizzard 1230-III 68030 @ 50MHz
  72.  
  73.     o If no requester (task, in fact) can be created alert message will be
  74.       shown instead. Information level of this alert is remarkably lower
  75.       than real crash requester's, but you usually never see this alert
  76.       message anyway.
  77.  
  78.     o SmartCrash is capable to skip failed instructions at least with 68020
  79.       and 68030 processors. 68040 and 68060 aren't tested and will not work
  80.       completely correctly. (Sorry that's the truth, boys and girls...;-)
  81.       With 68040 (and presumably 68060), in some cases, there is no way of
  82.       knowing when (for example) address error occured. There are some
  83.       common exceptions that work similarily in all MC680x0 family
  84.       processors, though. These include at least Trap #x instructions, Chk
  85.       instructions, Trapcc, Trapv etc. and they're usually called
  86.       "Exceptions Instructions". Address errors, bus errors, privilege
  87.       violations, illegal instructions (esp. illegal mmu instructions) can
  88.       cause unstabil (even false) results on '040 and '060.
  89.  
  90.     o Although SmartCrash patches one execbase function and TC_TRAPCODE
  91.       of many tasks it will always be possible to quit SmartCrash. The
  92.       little disadvantage is that 48 bytes of memory will be lost at every
  93.       quit. That isn't usually a big problem as programs like this are
  94.       rarely terminated. If some other program has patched the function
  95.       SmartCrash patches [that is exec.library/AddTask()] then this
  96.       function is left as it is (This prevents some potential crashes!).
  97.  
  98.     o There is an example failure program in this distribution archive.
  99.       It's called "CauseFailPro". It is the easiest (and safes) way to test
  100.       SmartCrash. Just press "Skip" -button of the crash requester to
  101.       proceed onwards in this avesome program :-). You can also hit "Exit"
  102.       -button without memory loss. The assembler source of this faulty
  103.       program is also included. (Gee!)
  104.  
  105.     o SmartCrash should be compatible with all future Kickstarts. Kickstart
  106.       3.0 is currently the only tested one. If SmartCrash refuses to
  107.       cooperate with other kickstarts then contact the author(s).
  108.  
  109.     o To contact the author(s) try these:
  110.  
  111.       Harry Sintonen (Delta)           (Gifts, cli-scripts, ASM Sources
  112.       Kotipolku 30                      etc. are welcome. No illegal trade.)
  113.       48710  Karhula
  114.       FINLAND
  115.  
  116.       Marko Nippula                    (2nd editor of the SmartCrash. He
  117.       E-Mail: mnippula@vipunen.hut.fi   might not be so interested about
  118.                                         this project nowadays though...:-)
  119.  
  120.  
  121.     *** SmartCrash's Usage  ***
  122.  
  123.     o SmartCrash's template is
  124.  
  125.       RT=USEREQTOOLS/S, RTFONTNAME, RTFONTSIZE/N
  126.  
  127.       RT=USEREQTOOLS/S          With this switch you can suggest SmartCrash
  128.                                 to use reqtools.library requesters instead
  129.                                 of intuition ones. If ReqTools isn't
  130.                                 available SmartCrash will fall back to
  131.                                 intuition requesters.
  132.  
  133.       RTFONTNAME                This parameter is valid when ReqTools
  134.                                 requester is in use. You can select the
  135.                                 font with the requester contents are shown.
  136.                                 (For example: RTFONTNAME="xen.font")
  137.  
  138.       RTFONTSIZE/N              Used with conjugation of RTFONTNAME. This
  139.                                 number specifies the font's height
  140.                                 (y-size). Default is 8 pixels.
  141.                                 (For example: RTFONTSIZE=9)
  142.  
  143.  
  144.     o When you execute SmartCrash it will install itself. No "Run" is
  145.       needed. Second execution will remove SmartCrash. SmartCrash should
  146.       always be capable to remove itself. If you have any SmartCrash
  147.       requesters up and you try to remove SmartCrash, removal will wait
  148.       until all the requesters are closed.
  149.  
  150.     o It's fairly good idea to install SmartCrash on to your system. Just
  151.       copy the SmartCrash executable to C: -drawer or somewhere within your
  152.       paths. Then just insert line like this...
  153.  
  154.       SmartCrash >NIL: USEREQTOOLS foobar.font 9
  155.  
  156.       ...to your s:startup-sequence or s:user-startup.
  157.  
  158.  
  159.     o RC (return code) is set:
  160.       OK (0)                    SmartCrash installed ok.
  161.       WARN (5)                  SmartCrash removed ok.
  162.       ERROR (10)                Things went wrong. Couldn't install!
  163.                                 Couldn't get memory?
  164.       FAIL  (37)                You don't have kickstart 2.0 or better.
  165.  
  166.  
  167.     o When crashes (failures) occure a huge requester will pop up showing
  168.       loads of information about the crash:
  169.  
  170. ____________________________________________________________________________________
  171. |SmartCrash 1.1 Copyright © 1995-1996 PitPlane Productions                       [_]
  172. ||¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯||
  173. ||   Exception 5: zero divide                                                     ||
  174. ||   Task: 1E275D20  PC: 1E26B6E2  SR: 0006  USP: 1E277A68  SSP: 1E001DB8         ||
  175. ||   D: 000000D0 000000D1 000000D2 000000D3 000000D4 000000D5 000000D6 000000D7   ||
  176. ||   A: 000000A0 000000A1 000000A2 000000A3 000000A4 1E26B6DE 000000A6 1E277A68   ||
  177. ||   S: 000000A0 000000A1 1E26B6DE 1E26B6B2 000000D0 000000D1 000000D2 000000D3   ||
  178. ||   S: 000000D4 00000001 1E271EFC 00F96C8C 00001000 1E276714 1E2784F8 000009A8   ||
  179. ||   Command: CLI[8]: causefailpro                                                ||
  180. ||                                                                                ||
  181. ||   PC=1E26B6E2 points to 'causefailpro', hunk 0000:0000006A                     ||
  182. ||   A5=1E26B6DE points to 'causefailpro', hunk 0000:00000066                     ||
  183. ||   S2=1E26B6DE points to 'causefailpro', hunk 0000:00000066                     ||
  184. ||   S3=1E26B6B2 points to 'causefailpro', hunk 0000:0000003A                     ||
  185. ||________________________________________________________________________________||
  186. |.---------.    .--------------.    .------.    .-------.    .--------.    .------.|
  187. || Suspend |    | Suspend&Free |    | Exit |    | Debug |    | Reboot |    | Skip ||
  188. |`---------'    `--------------'    `------'    `-------'    `--------'    `------'|
  189. ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  190.                 FIGURE 2: Great SmartCrash crash requester
  191.  
  192.  
  193.  
  194.       The extractions of the requester are marked with ->
  195.  
  196.  
  197.     -  The first line will show the exception occured:
  198.  
  199.     -> Exception 5: zero divide
  200.  
  201.  
  202.     -  The next line will contain information about the task crashed
  203.        (address of TC structure), program counter (PC, where error
  204.        occured), status register (SR, CPU state), user stack pointer (USP)
  205.        and supervisor stack pointer (SSP):
  206.  
  207.     -> Task: 1E275D20  PC: 1E26B6E2  SR: 0006  USP: 1E277A68  SSP: 1E001DB8
  208.  
  209.  
  210.     -  Next there are four lines containg information about the processor
  211.        registers and stack contents (first line: data registers, second line:
  212.        address registers, last two lines: stack contents):
  213.  
  214.     -> D: 000000D0 000000D1 000000D2 000000D3 000000D4 000000D5 000000D6 000000D7
  215.     -> A: 000000A0 000000A1 000000A2 000000A3 000000A4 1E26B6DE 000000A6 1E277A68
  216.     -> S: 000000A0 000000A1 1E26B6DE 1E26B6B2 000000D0 000000D1 000000D2 000000D3
  217.     -> S: 000000D4 00000001 1E271EFC 00F96C8C 00001000 1E276714 1E2784F8 000009A8
  218.  
  219.  
  220.     -  After these is line which give information about the program which
  221.        caused the trouble (is it a CLI command, process or a task and the
  222.        name of it):
  223.  
  224.     -> Command: CLI[8]: causefailpro
  225.  
  226.  
  227.     !  Now, if you don't have SegTracker program running on the background
  228.        requester's information ends here. In this case skip to
  229.        documentation of buttons.
  230.  
  231.  
  232.     -  Last there are varying number of lines giving SegTracker information
  233.        about some of the elements (program counter, registers, stack
  234.        contents):
  235.  
  236.     -> PC=1E26B6E2 points to 'causefailpro', hunk 0000:0000006A
  237.     -> A5=1E26B6DE points to 'causefailpro', hunk 0000:00000066
  238.     -> S2=1E26B6DE points to 'causefailpro', hunk 0000:00000066
  239.     -> S3=1E26B6B2 points to 'causefailpro', hunk 0000:0000003A
  240.  
  241.     -  PC points to program 'causefailpro', hunk 0, offset $6A.
  242.     -  A5 points to program 'causefailpro', hunk 0, offset $66.
  243.     -  Stack at position sp+8 contains pointer to program 'causefailpro' to
  244.        hunk 0, offset $66.
  245.     -  Stack at position sp+12 contains pointer to program 'causefailpro'
  246.        to hunk 0, offset $3A.
  247.     -  Note that there might be references to "strange" programs as
  248.        register and stack contents can be initially random. It's your task
  249.        to solve whether SegTracker reference is real one or not.
  250.  
  251.  
  252.     -  Buttons:
  253. ____________________________________________________________________________________
  254. |.---------.    .--------------.    .------.    .-------.    .--------.    .------.|
  255. || Suspend |    | Suspend&Free |    | Exit |    | Debug |    | Reboot |    | Skip ||
  256. |`---------'    `--------------'    `------'    `-------'    `--------'    `------'|
  257. ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  258.                FIGURE 3: All buttons in SmartCrash reguester
  259.  
  260.  
  261.        .---------.              This button works similarily to "Suspend"
  262.        | Suspend |              -button of system's crash requester. It
  263.        `---------'              just suspends the program in question.
  264.  
  265.        .--------------.         This gadgets tries to free as much
  266.        | Suspend&Free |         resources as possible allocated by the
  267.        `--------------'         program. If crashed program is a task or a
  268.                                 process the only effect (compared to
  269.                                 Suspend) is that the task will be removed,
  270.                                 not just suspended. If the process has a
  271.                                 CLI structure (that means it was executed
  272.                                 as a CLI command) the SegList of the
  273.                                 program will be released and current
  274.                                 input and output filehandles will be
  275.                                 closed (they'll be closed only if they're
  276.                                 different than the standard ones). This
  277.                                 operation should be considered as "hacky".
  278.  
  279.        .------.                 This gadget causes the program in question
  280.        | Exit |                 to quit with original stackpointer. This
  281.        `------'                 makes sense since sometimes you could
  282.                                 release a CLI/Shell for your use, esp. if
  283.                                 it's the only one available!!
  284.  
  285.        .-------.                Now this is magic! With this one you can
  286.        | Debug |                activate the debugger (ROMWack/SAD, you
  287.        `-------'                need to send DEL from your console to
  288.                                 actually activate the debugger). The crash
  289.                                 requester will pop up again after the
  290.                                 debugger returns.
  291.  
  292.        .--------.               This button does what the name says:
  293.        | Reboot |               reboots the machine. This button is quite
  294.        `--------'               useful when you feel like whanging "the
  295.                                 three keys of doom" as your glorious
  296.                                 program has fucked up everything again!!
  297.                                 :-) (And hey! This can be even faster than
  298.                                 rebooting from keyboard, at least on
  299.                                 some A1200s)
  300.  
  301.        .------.                 Now hold you horses!! This button gives you
  302.        | Skip |                 possibility to skip "bad" instructions!!!
  303.        `------'                 This function works at least on 68020 and
  304.                                 68030 based Amigas. Now, this skip is really
  305.                                 great esp. when you have forgotten the one
  306.                                 "Illegal" debug instruction into your 3meg
  307.                                 program and your program fails. You can
  308.                                 calmly skip the illegal instruction and
  309.                                 the program proceeds as nothing had
  310.                                 happened. (Well you might have to hit
  311.                                 "Skip" more than once, esp. if the illegal
  312.                                 stuff is in some tight loop). BTW: This
  313.                                 feature can be used when debugging
  314.                                 programs: you can insert illegal
  315.                                 instructions to places where you want to
  316.                                 see the contents of registers, stack
  317.                                 contents, state of the CPU etc. and then
  318.                                 skip the faulty instructions with this
  319.                                 button.
  320.  
  321.  
  322.  
  323.                                 Simple, ha?
  324.  
  325.                    And remember... Enjoy the SmartCrash!
  326.  
  327.  
  328.  
  329.     *** COPYRIGHTS ***
  330.  
  331.     All Amiga technology is Copyright © Amiga Technologies GmbH. All
  332.     rights reserved.
  333.  
  334.     Blizzard Turbo Boards are © 1994 phase 5 digital products. All rights
  335.     reserved.
  336.  
  337.     SegTracker is Copyright © Michael Sinz.
  338.  
  339.     Reqtools.library is Copyright © Nico François.
  340.  
  341.     SmartCrash is Copyright © 1995-1996 PitPlane Productions.
  342.  
  343.  
  344.     *** LICENSE ***
  345.  
  346. 1.   This license applies to the product called "SmartCrash", a program for
  347.      the Amiga computer, published by PitPlane Productions under the
  348.      concepts of FreeWare, and the accompanying documentation. The terms
  349.      "Program" and "SmartCrash" below, refer to this product. The licensee
  350.      is addressed as "you".
  351.  
  352. 2.   You may copy and distribute verbatim copies of the program's
  353.      executable code and documentation as you receive it, in any medium,
  354.      provided that you conspicuously and appropriately publish only the
  355.      original, unmodified program, with all copyright notices and
  356.      disclaimers of warranty intact and including all the accompanying
  357.      documentation, example files and anything else that came with the
  358.      original.
  359.  
  360. 3.   You may not copy and/or distribute this program without the
  361.      accompanying documentation and other additional files that came with
  362.      the original. You may not copy and/or distribute modified versions of
  363.      this program.
  364.  
  365. 4.   You may not copy, modify, sublicense, distribute or transfer the
  366.      program except as expressly provided under this license. Any attempt
  367.      otherwise to copy, modify, sublicense, distribute or transfer the
  368.      program is void, and will automatically terminate your rights to use
  369.      the program under this license. However, parties who have received
  370.      copies, or rights to use copies, from you under this license will not
  371.      have their licenses terminated so long as such parties remain in full
  372.      compliance.
  373.  
  374. 5.   By copying, distributing and/or using the program you indicate your
  375.      acceptance of this license to do so, and all its terms and conditions.
  376.  
  377. 6.   Each time you redistribute the program, the recipient automatically
  378.      receives a license from the original licensor to copy, distribute
  379.      and/or use the program subject to these terms and conditions. You may
  380.      not impose any further restrictions on the recipients' exercise of the
  381.      rights granted herein.
  382.  
  383. 7.   You may not disassemble, decompile, re-source or otherwise reverse
  384.      engineer the program.
  385.  
  386. 8.   If you wish to incorporate parts of the program into other programs,
  387.      write to the author to ask for permission.
  388.  
  389. 9.   You agree to cease distributing the program and data involved if
  390.      requested to do so by the author.
  391.  
  392. 10.  You may charge a fee to recover distribution costs. The fee for
  393.      diskette distribution may not be more than the cost to obtain a public
  394.      domain diskette from Fred Fish.
  395.  
  396.  
  397.     *** DISCLAIMER ***
  398.  
  399.      NO GUARANTEE IS GIVEN NOR IMPLIED THAT THIS PROGRAM IS FIT FOR ANY
  400.      USE. THIS PROGRAM AND THE INFORMATION WITHIN THIS TEXT IS PROVIDED ON
  401.      "AS IS" BASIS. THE ENTIRE RISK AS TO ITS QUALITY AND PERFORMANCE IS
  402.      WITH THE USER. SHOULD THE PROGRAM PROVE DEFECTIVE, THE USER (AND NOT
  403.      THE AUTHOR) ASSUMES THE ENTIRE COST OF ALL NECCESSARY DAMAGES. IN NO
  404.      EVENT WILL THE AUTHOR BE LIABLE FOR DIRECT, INDIRECT, INCIDENTAL OR
  405.      CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT IN THE PROGRAM. THE
  406.      AUTHOR RESERVES THE RIGHT TO MAKE CHANGES TO THE SOFTWARE OR
  407.      DOCUMENTATION WITHOUT NOTICE.
  408.